home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 February / EnigmA AMIGA RUN 15 (1997)(G.R. Edizioni)(IT)[!][issue 1997-02][PLANET CD V].iso / enigma / earcd / musicali / splib52d.lha / superplay-lib_DEV / Programmers / autodocs / SPObject_Ref_ENG.doc < prev    next >
Text File  |  1996-11-15  |  17KB  |  721 lines
  1. TABLE OF CONTENTS
  2.  
  3. SPObject.library/--background--
  4. SPObject.library/SPO_AllocHandle
  5. SPObject.library/SPO_FreeHandle
  6. SPObject.library/SPO_Read
  7. SPObject.library/SPO_StartReplay
  8. SPObject.library/SPO_Write
  9. SPObject.library/SPO_StopReplay
  10. SPObject.library/SPO_FreeResources
  11. SPObject.library/SPO_SetAccessMode
  12. SPObject.library/SPO_SetWriteSubType
  13. SPObject.library/SPO_SetWriteName
  14. SPObject.library/SPO_SetReadName
  15. SPObject.library/SPO_FileInfoRequest
  16. SPObject.library/SPO_CheckFileType
  17. SPObject.library/SPO_SetReqIOWindow
  18. SPObject.library/SPO_ContinueReplay
  19. SPObject.library/SPO_FastForward
  20. SPObject.library/SPO_FastBackward
  21. SPObject.library/SPO_GetSampleBuffer
  22. SPObject.library/SPO_GetSampleInfo
  23. SPObject.library/SPO_GetSampleList
  24. SPObject.library/SPO_SetSampleList
  25.  
  26.  SPObject.library/--background--
  27.  
  28.    VERSION
  29.         $VER: SPObject_Ref_ENG.doc V5.1 (8.8.96)
  30.  
  31.    COPYRIGHT
  32.         © 1995-96 by Andreas R. Kleinert. All rights reserved.
  33.       
  34.         - Feel free to translate this Doc-File into other languages. -
  35.  
  36.    GENERAL
  37.           Andreas R. Kleinert,
  38.           Sandstrasse 1,
  39.           D-57072 Siegen,
  40.           Germany.
  41.  
  42.         EMail:  Fido             Andreas Kleinert 2:2457/350.18
  43.                 Usenet/InterNet  Andreas_Kleinert@superview.ftn.sub.org
  44.     
  45.           If nothing else works, try one of these Fido-InterNet gateways:
  46.     
  47.                 Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (in Germany)
  48.                 Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org  (USA or other)
  49.  
  50.    NOTE
  51.         * DO _NEVER_ ACCESS ANY SPOBJECTS DIRECTLY.
  52.         * DO NEVER BYPASS superplay.library !
  53.     
  54.         THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SPOBJECTS :
  55.  
  56.  
  57.    HISTORY
  58.                             V2.5   Autodoc format
  59.                                    Change one SVO_ prefix to SPO_
  60.                                    Add version behind NAME
  61.                                    SPObject.library/SPO_SetReadeName
  62.                                                                ^
  63.                                      -> SPObject.library/SPO_SetReadName(indy)
  64.                             V5.1   applied some more changes (ak)
  65.  
  66.  SPObject.library/SPO_AllocHandle             SPObject.library/SPO_AllocHandle
  67.  
  68.    NAME
  69.         SPO_AllocHandle  (V1)
  70.  
  71.    SYNOPSIS
  72.  
  73.         APTR SPO_AllocHandle(APTR future)
  74.         D0   -$1e            A1
  75.  
  76.    FUNCTION
  77.  
  78.         Allocates a handle for accessing a Sample/Module via SPObjects.
  79.  
  80.    INPUT(S)
  81.  
  82.         future - always NULL yet
  83.  
  84.    RESULT
  85.  
  86.         A pointer to a new allocated Handle or NULL, if allocation failed.
  87.  
  88.    WARNING
  89.  
  90.         Test, if the result was NULL, or not !
  91.  
  92.    SEE ALSO
  93.  
  94.         SPO_FreeResources, SPO_FreeHandle
  95.  
  96.  SPObject.library/SPO_FreeHandle               SPObject.library/SPO_FreeHandle
  97.  
  98.    NAME
  99.         SPO_FreeHandle  (V1)
  100.  
  101.    SYNOPSIS
  102.  
  103.         VOID SPO_FreeHandle(APTR handle)
  104.         D0   -$24           A1
  105.  
  106.    FUNCTION
  107.  
  108.        Stops playing, frees all Resources and delocates a Handle, which has
  109.        been allocated with SPO_AllocHandle before.
  110.  
  111.    INPUT(S)
  112.  
  113.         handle - a valid handle
  114.  
  115.    RESULT
  116.  
  117.         -
  118.  
  119.    SEE ALSO
  120.  
  121.         SPO_AllocHandle, SPO_StopReplay, SPO_FreeResources
  122.  
  123.  SPObject.library/SPO_Read                           SPObject.library/SPO_Read
  124.  
  125.    NAME
  126.         SPO_Read  (V1)
  127.  
  128.    SYNOPSIS
  129.  
  130.         ULONG SPO_Read(APTR handle)
  131.         D0    -$2a     A1
  132.  
  133.    FUNCTION
  134.  
  135.         Loads the Sample/Module described by FileName, which then may
  136.         e.g. be replayed by SPO_StartReplay.
  137.  
  138.    INPUT(S)
  139.  
  140.         handle   - a valid handle
  141.  
  142.    RESULT
  143.  
  144.         NULL or an adequate SPERR-Errorcode.
  145.  
  146.    SEE ALSO
  147.  
  148.         SPO_AllocHandle, SPO_StopReplay, SPO_StartReplay, SPO_ContinueReplay,
  149.         SPO_FastForward, SPO_FastBackward, SPO_FreeHandle
  150.  
  151.  SPObject.library/SPO_StartReplay             SPObject.library/SPO_StartReplay
  152.  
  153.    NAME
  154.         SPO_StartReplay  (V1)
  155.  
  156.    SYNOPSIS
  157.  
  158.         ULONG SPO_StartReplay(APTR handle)
  159.         D0    -$30            A1
  160.  
  161.    FUNCTION
  162.  
  163.         Play the Sample/Module described by FileName, which has been loaded
  164.         via SPO_Read before.
  165.  
  166.         Playing can be stopped either via full delocation of the handle
  167.         or temporal interruption with SPO_StopReplay.
  168.  
  169.    INPUT(S)
  170.  
  171.         handle   - a valid handle
  172.  
  173.    RESULT
  174.  
  175.         NULL or an adequate SPERR-Errorcode.
  176.  
  177.    SEE ALSO
  178.  
  179.         SPO_AllocHandle, SPO_Read, SPO_StopReplay, SPO_ContinueReplay,
  180.         SPO_FastForward, SPO_FastBackward, SPO_FreeHandle
  181.  
  182.  SPObject.library/SPO_Write                         SPObject.library/SPO_Write
  183.  
  184.    NAME
  185.         SPO_Write  (V1)
  186.  
  187.    SYNOPSIS
  188.  
  189.         ULONG SPO_Write(APTR handle, struct SPObjectBase *SourceBase,
  190.         D0    -$36      A1           A2
  191.  
  192.                         APTR source_handle)
  193.                         A3
  194.  
  195.    FUNCTION
  196.  
  197.         This functions allows to access an other SPObject, get the Sample-
  198.         Data from there (only works with SampleType-SPObjects) and
  199.         then writes this data in its own FileFormat.
  200.  
  201.         If "SourceBase" and "source_handle" are both NULL,
  202.         it is checked, whether a SampleList has been set via
  203.         "SPO_SetSampleList()", and then this SampleList is completely
  204.         saved.
  205.  
  206.    INPUT(S)
  207.  
  208.         handle        - a valid handle
  209.                         (used for Write Access)
  210.         SourceBase    - pointer to Base of other SPObject
  211.                         (may be NULL for V2+ SPObjects)
  212.         source_handle - handle for accessing the other SPObject
  213.                         (may be NULL for V2+ SPObjects)
  214.  
  215.    RESULT
  216.  
  217.         NULL or an adequate SPERR-Errorcode.
  218.  
  219.    SEE ALSO
  220.  
  221.         SPO_AllocHandle, SPO_Read, SPO_FreeHandle
  222.  
  223.  SPObject.library/SPO_StopReplay               SPObject.library/SPO_StopReplay
  224.  
  225.    NAME
  226.         SPO_StopReplay  (V1)
  227.  
  228.    SYNOPSIS
  229.  
  230.         VOID SPO_StopReplay(APTR handle)
  231.         D0   -$3c           A1
  232.  
  233.    FUNCTION
  234.  
  235.         Stops playing the Sample/Module, indentified by the handle.
  236.         Some SPObjects support to continue the Sample/Module with
  237.         SPO_ContinueReplay after calling SPO_StopReplay.
  238.  
  239.    INPUT(S)
  240.  
  241.         handle - a valid handle
  242.  
  243.    RESULT
  244.  
  245.         -
  246.  
  247.    SEE ALSO
  248.  
  249.         SPO_ContinueReplay, SPO_FreeResources, SPO_FreeHandle
  250.  
  251.  SPObject.library/SPO_FreeResources         SPObject.library/SPO_FreeResources
  252.  
  253.    NAME
  254.         SPO_FreeResources  (V1)
  255.  
  256.    SYNOPSIS
  257.  
  258.         VOID SPO_FreeResources(APTR handle)
  259.         D0   -$42              A1
  260.  
  261.    FUNCTION
  262.  
  263.         Frees all resources belonging to the specific Sample/Module,
  264.         indentified by the handle, which are not needed to just replay it.
  265.         Playing of the Sample/Module is not stopped and/or interrupted.
  266.  
  267.    INPUT(S)
  268.  
  269.         handle - a valid handle
  270.  
  271.    RESULT
  272.  
  273.         -
  274.  
  275.    SEE ALSO
  276.  
  277.         SPO_AllocHandle, SPO_StopReplay, SPO_FreeHandle
  278.  
  279.  SPObject.library/SPO_SetAccessMode         SPObject.library/SPO_SetAccessMode
  280.  
  281.    NAME
  282.         SPO_SetAccessMode  (V1)
  283.  
  284.    SYNOPSIS
  285.  
  286.         ULONG SPO_SetAccessMode(APTR handle, ULONG mode)
  287.         D0    -$48              A1           D1
  288.  
  289.    FUNCTION
  290.  
  291.         Initializes a Handle for ClipBoard or AmigaDOS access,
  292.         depending on the "mode" parameter.
  293.  
  294.    INPUT(S)
  295.  
  296.         handle - a valid handle
  297.         mode   - access mode value
  298.  
  299.  
  300.    RESULT
  301.  
  302.         NULL or an adequate SPERR-Errorcode.
  303.  
  304.    SEE ALSO
  305.  
  306.         -
  307.  
  308.  SPObject.library/SPO_SetWriteSubType     SPObject.library/SPO_SetWriteSubType
  309.  
  310.    NAME
  311.         SPO_SetWriteSubType  (V1)
  312.  
  313.    SYNOPSIS
  314.  
  315.         ULONG SPO_SetWriteSubType(APTR handle, ULONG write_type, APTR future)
  316.         D0    -$4e                A1           A2                A3
  317.  
  318.    FUNCTION
  319.  
  320.         Sets the write_type for a SPO_Write() call.
  321.         See description there and example SourceCodes for more and
  322.         detailed information.
  323.  
  324.    INPUT(S)
  325.  
  326.         handle     - a valid handle
  327.         write_type - a valid temporary write_type code form the SPObject List
  328.         future     - always NULL yet
  329.  
  330.  
  331.    RESULT
  332.  
  333.         NULL or an adequate SPERR-Errorcode.
  334.  
  335.    SEE ALSO
  336.  
  337.         SPO_Write
  338.  
  339.  SPObject.library/SPO_SetWriteName           SPObject.library/SPO_SetWriteName
  340.  
  341.    NAME
  342.         SPO_SetWriteName  (V1)
  343.  
  344.    SYNOPSIS
  345.  
  346.         ULONG SPO_SetWriteName(APTR handle, UBYTE *write_name, APTR future)
  347.         D0    -$54             A1           A2                 A3
  348.  
  349.    FUNCTION
  350.  
  351.         Sets the write_name for a SPO_Write() call.
  352.         See description there and example SourceCodes for more and
  353.         detailed information.
  354.  
  355.    INPUT(S)
  356.  
  357.         handle     - a valid handle
  358.         write_name - a valid AmigaDOS FilePath and -Name description
  359.         future     - always NULL yet
  360.  
  361.  
  362.    RESULT
  363.  
  364.         NULL or an adequate SPERR-Errorcode.
  365.  
  366.    SEE ALSO
  367.  
  368.         SPO_Write
  369.  
  370.  SPObject.library/SPO_SetReadName             SPObject.library/SPO_SetReadName
  371.  
  372.    NAME
  373.         SPO_SetReadName  (V1)
  374.  
  375.    SYNOPSIS
  376.  
  377.         ULONG SPO_SetReadName(APTR handle, ULONG reade_name, APTR future)
  378.         D0    -$5a            A1           A2                A3
  379.  
  380.    FUNCTION
  381.  
  382.         Sets the reade_name for a SPO_Read() call.
  383.         See description there and example SourceCodes for more and
  384.         detailed information.
  385.  
  386.    INPUT(S)
  387.  
  388.         handle     - a valid handle
  389.         write_name - a valid AmigaDOS FilePath and -Name description
  390.         future     - always NULL yet
  391.  
  392.  
  393.    RESULT
  394.  
  395.         NULL or an adequate SPERR-Errorcode.
  396.  
  397.    SEE ALSO
  398.  
  399.         SPO_Write
  400.  
  401.  SPObject.library/SPO_FileInfoRequest     SPObject.library/SPO_FileInfoRequest
  402.  
  403.    NAME
  404.         SPO_FileInfoRequest  (V1)
  405.  
  406.    SYNOPSIS
  407.  
  408.         ULONG SPO_FileInfoRequest(APTR handle, struct Window *window,
  409.         D0    -$60                A1           A2
  410.  
  411.                                   APTR future)
  412.                                   A3
  413.  
  414.    FUNCTION
  415.  
  416.         Pops up an Info-Requester with more or less detailed information
  417.         on the currently loaded Sample/Module.
  418.         A window pointer may be given to select the place to pop it up.
  419.  
  420.    INPUT(S)
  421.  
  422.         handle - a valid handle
  423.         window - a valid Window Pointer or NULL
  424.         future - always NULL yet
  425.  
  426.  
  427.    RESULT
  428.  
  429.         NULL or an adequate SPERR-Errorcode.
  430.  
  431.    SEE ALSO
  432.  
  433.         SPO_SetReqIOWindow
  434.  
  435.  SPObject.library/SPO_CheckFileType         SPObject.library/SPO_CheckFileType
  436.  
  437.    NAME
  438.         SPO_CheckFileType  (V1)
  439.  
  440.    SYNOPSIS
  441.  
  442.         ULONG SPO_CheckFileType(BPTR filehandle, UBYTE *filename,
  443.         D0    -$66              A1                 A2
  444.  
  445.                                 struct SPOCheckFile *spo_check)
  446.                                 A3
  447.  
  448.    FUNCTION
  449.  
  450.         Checks, if the given file (or ClipBoard entry, or whatever)
  451.         fits to this SPObject and can be handled therein.
  452.  
  453.         Other media as SPO_MEDIUM_DISK requite spo_check to
  454.         be non-NULL and initialized.
  455.  
  456.         Be prepared, to handle NULL pointers to filename and handle.
  457.  
  458.    INPUT(S)
  459.  
  460.         handle    - a valid handle
  461.         name      - a valid AmigaDOS FileName
  462.         spo_check - a pointer to a SPOCheckFile structure or NULL
  463.                     for disk-access (default)
  464.  
  465.    RESULT
  466.  
  467.         NULL or an adequate SVERR-Errorcode.
  468.  
  469.    SEE ALSO
  470.  
  471.         -
  472.  
  473.  SPObject.library/SPO_SetReqIOWindow       SPObject.library/SPO_SetReqIOWindow
  474.  
  475.    NAME
  476.         SPO_SetReqIOWindow  (V1)
  477.  
  478.    SYNOPSIS
  479.  
  480.         ULONG SPO_SetReqIOWindow(APTR handle, struct Window *window)
  481.         D0    -$6c               A1           A2
  482.  
  483.    FUNCTION
  484.  
  485.         Sets a new Default-Window (default : IntuitionBase->FirstWindow)
  486.         for any Requester IO.
  487.  
  488.    INPUT(S)
  489.  
  490.         handle - a valid handle
  491.         window - a valid Window Pointer or NULL
  492.  
  493.    RESULT
  494.  
  495.         NULL or an adequate SPERR-Errorcode.
  496.  
  497.    SEE ALSO
  498.  
  499.         SPO_FileInfoReq
  500.  
  501.  SPObject.library/SPO_ContinueReplay       SPObject.library/SPO_ContinueReplay
  502.  
  503.    NAME
  504.         SPO_ContinueReplay  (V1)
  505.  
  506.    SYNOPSIS
  507.  
  508.         ULONG SPO_ContinueReplay(APTR handle)
  509.         D0    -$72               A1
  510.  
  511.    FUNCTION
  512.  
  513.         Some SPObjects support to continue a Sample/Module which
  514.         has been stopped by calling SPO_StopReplay.
  515.  
  516.    INPUT(S)
  517.  
  518.         handle - a valid handle
  519.  
  520.    RESULT
  521.  
  522.         NULL or an adequate SPERR-Errorcode.
  523.  
  524.    SEE ALSO
  525.  
  526.         SPO_SuperPlay, SPO_StopReplay
  527.  
  528.  SPObject.library/SPO_FastForward             SPObject.library/SPO_FastForward
  529.  
  530.    NAME
  531.         SPO_FastForward  (V1)
  532.  
  533.    SYNOPSIS
  534.  
  535.         ULONG SPO_FastForward(APTR handle)
  536.         D0    -$78            A1
  537.  
  538.    FUNCTION
  539.  
  540.         Some SPObjects might support a "cassette recorder"-like way
  541.         to browse trough a Sample/Module via FastForward and Rewind.
  542.  
  543.    INPUT(S)
  544.  
  545.         handle - a valid handle
  546.  
  547.    RESULT
  548.  
  549.         NULL or an adequate SPERR-Errorcode.
  550.  
  551.    SEE ALSO
  552.  
  553.         SPO_FastBackward
  554.  
  555.  SPObject.library/SPO_FastBackward           SPObject.library/SPO_FastBackward
  556.  
  557.    NAME
  558.         SPO_FastBackward  (V1)
  559.  
  560.    SYNOPSIS
  561.  
  562.         ULONG SPO_FastBackward(APTR handle)
  563.         D0    -$7e            A1
  564.  
  565.    FUNCTION
  566.  
  567.         Some SPObjects might support a "cassette recorder"-like way
  568.         to browse trough a Sample/Module via FastForward and Rewind.
  569.  
  570.    INPUT(S)
  571.  
  572.         handle - a valid handle
  573.  
  574.    RESULT
  575.  
  576.         NULL or an adequate SPERR-Errorcode.
  577.  
  578.    SEE ALSO
  579.  
  580.         SPO_FastForward
  581.  
  582.  SPObject.library/SPO_GetSampleBuffer     SPObject.library/SPO_GetSampleBuffer
  583.  
  584.    NAME
  585.         SPO_GetSampleBuffer  (V1)   *** OBSOLETE : Use SPO_GetSampleList()
  586.  
  587.    SYNOPSIS
  588.  
  589.         ULONG SPO_GetSampleBuffer(APTR handle, UBYTE **buffer,
  590.         D0    -$84                A1           A2
  591.  
  592.                                   ULONG *buffersize)
  593.                                   A3
  594.  
  595.    FUNCTION
  596.  
  597.         This function is OBSOLETE. Don't use it.
  598.  
  599.         Use SPO_GetSampleList instead, which can handle more than one
  600.         Sample and also returns the information related to them.
  601.  
  602.    INPUT(S)
  603.  
  604.         handle     - a valid handle
  605.         buffer     - a pointer to a buffer pointer
  606.         buffersize - a pointer to a buffersize pointer
  607.  
  608.    RESULT
  609.  
  610.         NULL or an adequate SPERR-Errorcode.
  611.  
  612.    SEE ALSO
  613.  
  614.         SPO_GetSampleList
  615.  
  616.  SPObject.library/SPO_GetSampleInfo         SPObject.library/SPO_GetSampleInfo
  617.  
  618.    NAME
  619.         SPO_GetSampleInfo  (V1)     *** OBSOLETE : Use SPO_GetSampleList()
  620.  
  621.    SYNOPSIS
  622.  
  623.         ULONG SPO_GetSampleInfo(APTR handle, ULONG *samplesPerSec,
  624.         D0    -$8a              A1           A2
  625.  
  626.                                 ULONG *volume, APTR future)
  627.                                 A3             D1
  628.  
  629.    FUNCTION
  630.  
  631.         This function is OBSOLETE. Don't use it.
  632.  
  633.         Use SPO_GetSampleList instead, which can handle more than one
  634.         Sample and also returns the information related to them.
  635.  
  636.         This function only returns info on 8 Bit Samples.
  637.  
  638.    INPUT(S)
  639.  
  640.         handle        - a valid handle
  641.         samplesPerSec - a pointer to a buffer pointer
  642.         volume        - a pointer to a buffersize pointer
  643.         future        - always NULL yet
  644.  
  645.    RESULT
  646.  
  647.         NULL or an adequate SPERR-Errorcode.
  648.  
  649.    SEE ALSO
  650.  
  651.         SPO_GetSampleList
  652.  
  653.  SPObject.library/SPO_GetSampleList         SPObject.library/SPO_GetSampleList
  654.  
  655.    NAME
  656.         SPO_GetSampleList  (V2)
  657.  
  658.    SYNOPSIS
  659.  
  660.         ULONG SPO_GetSampleList(APTR handle, struct SPO_SampleList **list)
  661.         D0    -$90              A1           A2
  662.  
  663.    FUNCTION
  664.  
  665.         While/after loading a Sample-File SPObjects might create
  666.         a special list of all Samples, which appear in the File.
  667.         This will usually be one one Sample for SampleFiles, but many more
  668.         for ModuleFiles.
  669.  
  670.         Not all SPObjects, especially not all ModuleType-SPObjects,
  671.         may support this and will return an error value or an empty list.
  672.  
  673.    INPUT(S)
  674.  
  675.         handle - a valid handle
  676.         list   - a pointer to a SPO_SampleList pointer
  677.  
  678.    RESULT
  679.  
  680.         NULL or an adequate SPERR-Errorcode.
  681.  
  682.    SEE ALSO
  683.  
  684.         SPO_SetSampleList
  685.  
  686.  SPObject.library/SPO_SetSampleList         SPObject.library/SPO_SetSampleList
  687.  
  688.    NAME
  689.         SPO_SetSampleList  (V2)
  690.  
  691.    SYNOPSIS
  692.  
  693.         ULONG SPO_SetSampleList(APTR handle, struct SPO_SampleList *list)
  694.         D0    -$96              A1           A2
  695.  
  696.    FUNCTION
  697.  
  698.         For saving Sample-Files with, there may be used
  699.         a special list of all Samples, which should appear in the File.
  700.  
  701.         This will usually be one one Sample for SampleFiles, but many more
  702.         for ModuleFiles.
  703.  
  704.         Not all SPObjects, especially not all ModuleType-SPObjects,
  705.         may support this and will return SPERR_ACTION_NOT_SUPPORTED.
  706.  
  707.    INPUT(S)
  708.  
  709.         handle - a valid handle
  710.         list   - a pointer to a SPO_SampleList
  711.  
  712.    RESULT
  713.  
  714.         NULL or an adequate SPERR-Errorcode.
  715.  
  716.    SEE ALSO
  717.  
  718.         SPO_GetSampleList
  719.  
  720.  
  721.